fastify-plugin

What is fastify-plugin?

The fastify-plugin npm package is designed to facilitate the creation of plugins for the Fastify web framework. It ensures that plugins adhere to specific conventions and are compatible with the Fastify ecosystem. This package helps in encapsulating functionality, adding hooks, decorators, and more, in a way that's easily reusable across different Fastify projects.

What are fastify-plugin's main functionalities?

Plugin Creation

This feature allows developers to create a Fastify plugin. The code sample demonstrates how to use fastify-plugin to decorate the Fastify instance with a new function called 'utility'.

const fp = require('fastify-plugin');

async function myPlugin (fastify, options) {
  fastify.decorate('utility', () => 'something useful');
}

module.exports = fp(myPlugin);

Plugin Options

This feature enables passing options to the plugin, including specifying Fastify version compatibility. The code sample shows how to pass data through options and use it within the plugin.

const fp = require('fastify-plugin');

async function myPlugin (fastify, options) {
  fastify.decorate('usefulData', options.data);
}

module.exports = fp(myPlugin, { name: 'myPlugin', fastify: '3.x' });

Encapsulation

This feature ensures that the plugin does not encapsulate its context, allowing the decorators, hooks, and changes made by the plugin to be available in the parent scope. The code sample demonstrates registering another plugin within a fastify-plugin, ensuring dependencies are managed.

const fp = require('fastify-plugin');

async function myPlugin (fastify, options) {
  fastify.register(require('some-other-plugin'), options);
}

module.exports = fp(myPlugin, { dependencies: ['some-other-plugin'] });

Other packages similar to fastify-plugin

fastify-decorators

Provides decorators for Fastify, aiming to simplify the creation of controllers, services, and plugins. While it offers a different approach by leveraging TypeScript decorators, it shares the goal of enhancing Fastify's extensibility.

middie

A plugin to add middleware support to Fastify. While fastify-plugin is a tool for creating Fastify plugins, middie focuses specifically on enabling the use of Express/Connect-style middleware within Fastify applications.

fastify-autoload

Automatically loads plugins and routes, simplifying the application structure. Unlike fastify-plugin, which is about creating plugins, fastify-autoload helps in organizing and loading them efficiently in a Fastify application.

README

fastify-plugin

fastify-plugin is a plugin helper for Fastify.

When you build plugins for Fastify and you want them to be accessible in the same context where you require them, you have two ways:

1. Use the skip-override hidden property
2. Use this module

Note: the v4.x series of this module covers Fastify v4 Note: the v2.x & v3.x series of this module covers Fastify v3. For Fastify v2 support, refer to the v1.x series.

Install

npm i fastify-plugin

Usage

fastify-plugin can do three things for you:

• Add the skip-override hidden property
• Check the bare-minimum version of Fastify
• Pass some custom metadata of the plugin to Fastify

Example using a callback:

const fp = require('fastify-plugin')

module.exports = fp(function (fastify, opts, done) {
  // your plugin code
  done()
})

Example using an async function:

const fp = require('fastify-plugin')

// A callback function param is not required for async functions
module.exports = fp(async function (fastify, opts) {
  // Wait for an async function to fulfill promise before proceeding
  await exampleAsyncFunction()
})

Metadata

In addition, if you use this module when creating new plugins, you can declare the dependencies, the name, and the expected Fastify version that your plugin needs.

Fastify version

If you need to set a bare-minimum version of Fastify for your plugin, just add the semver range that you need:

const fp = require('fastify-plugin')

module.exports = fp(function (fastify, opts, done) {
  // your plugin code
  done()
}, { fastify: '5.x' })

If you need to check the Fastify version only, you can pass just the version string.

You can check here how to define a semver range.

Name

Fastify uses this option to validate the dependency graph, allowing it to ensure that no name collisions occur and making it possible to perform dependency checks.

const fp = require('fastify-plugin')

function plugin (fastify, opts, done) {
  // your plugin code
  done()
}

module.exports = fp(plugin, {
  fastify: '5.x',
  name: 'your-plugin-name'
})

Dependencies

You can also check if the plugins and decorators that your plugin intend to use are present in the dependency graph.

Note: This is the point where registering name of the plugins become important, because you can reference plugin dependencies by their name.

const fp = require('fastify-plugin')

function plugin (fastify, opts, done) {
  // your plugin code
  done()
}

module.exports = fp(plugin, {
  fastify: '5.x',
  decorators: {
    fastify: ['plugin1', 'plugin2'],
    reply: ['compress']
  },
  dependencies: ['plugin1-name', 'plugin2-name']
})

Encapsulate

By default, fastify-plugin breaks the encapsulation but you can optionally keep the plugin encapsulated. This allows you to set the plugin's name and validate its dependencies without making the plugin accessible.

const fp = require('fastify-plugin')

function plugin (fastify, opts, done) {
  // the decorator is not accessible outside this plugin
  fastify.decorate('util', function() {})
  done()
}

module.exports = fp(plugin, {
  name: 'my-encapsulated-plugin',
  fastify: '5.x',
  decorators: {
    fastify: ['plugin1', 'plugin2'],
    reply: ['compress']
  },
  dependencies: ['plugin1-name', 'plugin2-name'],
  encapsulate: true
})

Bundlers and Typescript

fastify-plugin adds a .default and [name] property to the passed in function. The type definition would have to be updated to leverage this.

Known Issue: TypeScript Contextual Inference

Documentation Reference

It is common for developers to inline their plugin with fastify-plugin such as:

fp((fastify, opts, done) => { done() })
fp(async (fastify, opts) => { return })

TypeScript can sometimes infer the types of the arguments for these functions. Plugins in Fastify are recommended to be typed using either FastifyPluginCallback or FastifyPluginAsync. These two definitions only differ in two ways:

1. The third argument done (the callback part)
2. The return type FastifyPluginCallback or FastifyPluginAsync

At this time, TypeScript inference is not smart enough to differentiate by definition argument length alone.

Thus, if you are a TypeScript developer please use on the following patterns instead:

// Callback

// Assign type directly
const pluginCallback: FastifyPluginCallback = (fastify, options, done) => { }
fp(pluginCallback)

// or define your own function declaration that satisfies the existing definitions
const pluginCallbackWithTypes = (fastify: FastifyInstance, options: FastifyPluginOptions, done: (error?: FastifyError) => void): void => { }
fp(pluginCallbackWithTypes)
// or inline
fp((fastify: FastifyInstance, options: FastifyPluginOptions, done: (error?: FastifyError) => void): void => { })

// Async

// Assign type directly
const pluginAsync: FastifyPluginAsync = async (fastify, options) => { }
fp(pluginAsync)

// or define your own function declaration that satisfies the existing definitions
const pluginAsyncWithTypes = async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { }
fp(pluginAsyncWithTypes)
// or inline
fp(async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { })

Acknowledgements

This project is kindly sponsored by:

• nearForm
• LetzDoIt

License

Licensed under MIT.